Paymasters
Paymasters are a key component of the Account Abstraction ecosystem, enabling gasless transactions by sponsoring the gas fees on behalf of users.
What is a Paymaster?​
A Paymaster is a smart contract that decides whether to sponsor a user's transaction and how to pay for it. It can implement various business models, such as:
- Sponsoring all transactions for certain users
- Accepting ERC-20 tokens as payment for gas
- Implementing subscription-based models
- Offering free transactions with certain conditions
How Paymasters Work​
- The user creates a UserOperation (a transaction request)
- The UserOperation is sent to the Paymaster for approval
- The Paymaster verifies if it will sponsor the transaction
- If approved, the Paymaster signs the transaction and adds its details
- The bundler includes the transaction in a bundle for execution
Using Paymasters with 0xGasless​
The 0xGasless SDK handles Paymaster interactions transparently:
// Create a transaction with Paymaster sponsorship
const tx = await wallet.transfer({
to: '0xRecipientAddress',
token: '0xTokenContractAddress',
amount: '0.01',
usePaymaster: true, // Enable Paymaster sponsorship
});
// For token-based gas payment
const tx = await wallet.transfer({
to: '0xRecipientAddress',
token: 'native',
amount: '0.01',
paymentToken: '0xUSDCAddress', // Pay gas fees with USDC
});
Types of Paymasters​
Verifying Paymaster​
The Verifying Paymaster requires a signature to validate the UserOperation. This signature can be obtained from a server after performing any necessary verification checks.
// Initialize a Verifying Paymaster
const verifyingPaymaster = new VerifyingPaymaster({
paymasterUrl: "https://paymaster.0xgasless.com/api/v1/paymaster/",
entryPointAddress: ENTRYPOINT_ADDRESS,
chainId: CHAIN_ID,
});
// Use the paymaster for a transaction
const result = await smartAccount.sendTransaction({
to: recipient,
data: callData,
paymasterServiceData: {
paymaster: verifyingPaymaster,
// Optional: Custom data required by the paymaster
paymasterData: {
sessionId: "your-session-id",
policyId: "your-policy-id"
}
}
});
Token Paymaster​
The Token Paymaster allows users to pay for gas fees using ERC-20 tokens instead of the native blockchain currency. This is particularly useful for users who don't hold ETH but have other tokens.
// Initialize a Token Paymaster
const tokenPaymaster = new TokenPaymaster({
tokenAddress: "0xUSDCTokenAddress",
entryPointAddress: ENTRYPOINT_ADDRESS,
chainId: CHAIN_ID,
});
// Use the token paymaster for a transaction
const result = await smartAccount.sendTransaction({
to: recipient,
data: callData,
paymasterServiceData: {
paymaster: tokenPaymaster,
paymasterData: {
tokenGasPrice: "1000000000" // Token price in wei
}
}
});
ERC-20 Transfer with Token Paymaster​
Here's an example of transferring ERC-20 tokens while using another token to pay for gas:
import { TokenPaymaster } from "@0xgasless/smart-account";
import { encodeFunctionData, parseAbi } from "viem";
// ERC-20 token to transfer
const tokenToTransfer = "0xTokenToTransferAddress";
// Token to use for gas payment
const gasToken = "0xGasTokenAddress";
// Initialize token paymaster
const tokenPaymaster = new TokenPaymaster({
tokenAddress: gasToken,
entryPointAddress: ENTRYPOINT_ADDRESS,
chainId: CHAIN_ID,
});
// Encode ERC-20 transfer call
const transferAbi = parseAbi(["function transfer(address to, uint256 amount)"]);
const transferCalldata = encodeFunctionData({
abi: transferAbi,
functionName: "transfer",
args: [recipientAddress, "1000000000000000000"] // 1 token with 18 decimals
});
// Send transaction using token paymaster
const txResponse = await smartAccount.sendTransaction({
to: tokenToTransfer,
data: transferCalldata,
paymasterServiceData: {
paymaster: tokenPaymaster
}
});
console.log("Transaction Hash:", await txResponse.waitForTxHash());
0xGasless Paymaster Dashboard​
0xGasless provides a comprehensive dashboard for managing your paymasters. Visit https://dashboard.0xgasless.com to:
- Create new paymasters
- Manage paymaster funds
Best Practices​
- Security First: Always validate UserOperations before sponsoring them to prevent abuse
- Gas Efficiency: Implement gas-efficient validation logic in your paymasters
- Fallback Mechanism: Have a fallback mechanism if paymaster funds are depleted
- Monitoring: Set up alerts for low paymaster balances
- Rate Limiting: Implement rate limiting to prevent abuse
Troubleshooting​
Common Issues​
- Insufficient Paymaster Balance: Ensure your paymaster contract has sufficient funds
- Validation Failure: Check that the UserOperation meets all validation criteria
- Gas Estimation Errors: Verify gas parameters are set correctly
- Signature Verification Issues: Ensure signatures are created and verified correctly
For more assistance with paymasters, visit our Discord community or contact our support team.